Using TCP/IP Services (IM: OT)

Inside Macintosh: Open Transport /: Chapter 8 - TCP/IP Services

Using TCP/IP Services
This section describes how to use the Open Transport RawIP interface, how to implement IP multicasting, and how to use a variety of Open Transport endpoint and mapper functions with the TCP/IP protocols. TCP/IP options are described in "Options," beginning on page 8-28.

Using RawIP
The Open Transport TCP/IP software modules provide a RawIP interface to the IP protocol. The RawIP interface is provided to facilitate the implementation of new protocols that use IP for datagram delivery. Therefore, in order to use a RawIP endpoint, you must specify a value for the Protocol field in the IP datgram header. By default, RawIP fills in the Protocol field with a 1, indicating the packet carries an ICMP message. You can specify a different protocol type for a RawIP endpoint by using the option XTI_PROTOTYPE, described in the chapter "Option Management" in this book. The option value consists of a longword containing the number of the protocol to be used by the RawIP endpoint.
All RawIP endpoints using a specific protocol receive a copy of any inbound packets destined for that protocol. Thus, if several programs were using ICMP on the same host, they would all receive a copy of every inbound ICMP datagram.
The data delivered to a RawIP endpoint includes the full IP header, which is
20 bytes long if it includes no options.

WARNING
If you open a RawIP endpoint, you are responsible for implementing the protocol that is a client of IP running over that endpoint. Because an improperly implemented protocol can cause the host to crash or cause the loss of data on the network, you should not attempt to use RawIP unless you are an expert network programmer.

Using IP Multicasting
Open Transport TCP/IP provides IP multicasting level 2, as described in RFC 1112. To join a multicast group, use the IP_ADD_MEMBERSHIP option (page 8-35), passing in a TIPAddMulticast structure to specify the address and network interface of the group you wish to join. For a multihomed system, you can use the value kOTAnyInetAddress for the interface address to use the default multicast interface.
The time-to-live value for outbound multicast data defaults to 1; you can use the IP_MULTICAST_TTL option to set a different value. The time-to-live value is a hop count: Each router that processes the datagram decrements the Time to Live field and discards the datagram if the value reaches 0. Because every router that receives a multicast packet forwards it, a high time-to-live value for a multicast packet can cause the packet to propagate widely through the internet. Therefore, keep this value as low as possible.
By default, Open Transport IP loops back multicast datagrams to any
member of the group on the sending machine. Pass a value of T_NO to
the IP_MULTICAST_LOOP option to turn off loopbacks.

Using the Hosts File
The Open Transport DNR supports use of a Hosts file, which is located in the Preferences folder in the System Folder. The DNR parses the Hosts file when TCP/IP is loaded and uses it to initialize its list of host addresses, aliases, and name servers.

Note
Because the DNR downloads the information in the Hosts file and keeps it in RAM, a large Hosts files waste memory and degrades the performance of the DNR. Therefore, you should avoid using a Hosts file, or if you must use one, keep the Hosts file as small as possible.
The Hosts file can include lines of data, blank lines, and comments. A comment begins with a semicolon (;) and can be on the same line as data. The comment extends from the semicolon to the end of the line.
A data line in the Hosts file has either of the following two formats (the square brackets indicate an optional element):
domain-name [time-to-live IN] type rdata
domain-name [IN time-to-live] type rdata
The elements are defined as follows:

domain-name
An absolute or fully qualified domain name unless the data type is CNAME, in which case the name can be an alias. It need not be terminated by a period (.), but must contain at least one period internally.
time-to-live
The record's configured lifetime, in seconds. If this field is not present, the DNR assumes the entry has an infinite lifetime. You can also specify -1 for the time to live to indicate an infinite lifetime.
IN
The data class; always IN indicating the internet domain.
type
The type of data. This field can be A for a host address, CNAME for the canonical name of an alias, or NS for a
name server. Other DNS types are not supported in the Hosts file.
rdata
The data. For the A data type, this field must be an address in dotted-decimal format. For the CNAME and NS data types, this field must be a fully qualified domain name.
Here are some sample data lines:
apple.com A 130.43.2.2 ;address of host apple.com
rivers IN CNAME rivers.apple.com;canonical name of the host 
                              ; whose local alias is "rivers"
mit.edu. 86400 NS achilles.mit.edu;name server for mit.edu
                              ; domain. Entry has a 1-week
                              ; lifetime
Querying DNS Servers
In addition to the explicit simplified functions that are provided for the most commonly made queries such as name-to-address, address-to-name, system CPU and OS, and mail exchange queries, there is a generic query function, OTInetQuery, that you can use for any DNS query.
The OTInetQuery function allows you to use the Domain Name Resolver (DNR) for generic domain name service (DNS) queries. You can ask for any query type and class, and in response, Open Transport returns as many DNSQueryInfo structures as it can fit in the buffer you provide.
There are three types of responses: answers, authority responses, or additional information, and there are typically several of each type. Each response has its own DNSQueryInfo structure, with all the answers first, then all the authority records, then all the additional information. Authority responses refer you to DNS servers and other sources that may have helpful information for this answer and additional responses provide address data for the servers and sources referred to in the authority records.
If, for example, you use the OTInetQuery function to find out the IP addresses for a name, you might get back 13 DNSQueryInfo structures in your answer buffer: With, say, 2 IP address structures, 4 authority responses, and 7 additional information responses.
To help you parse this huge answer buffer, Open Transport provides two optional parameters for the OTInetQuery function, argv and argvlen, that create an array pointing to the individual responses.

Using General Open Transport Functions With TCP/IP
This section describes any special considerations that you must take into account for Open Transport functions when you use them with the Open Transport TCP/IP implementation. You should be familiar with the function descriptions in the chapters "Endpoints" and "Mappers" in this book before reading this section.

Obtaining Endpoint Data With TCP/IP
The following values can be returned by the info parameter to the OTOpenEndpoint, OTAsyncOpenEndpoint, and OTGetEndpointInfo functions when used with TCP/IP protocols:
Parameter TCP RawIP and UDP Meaning
info->addr T_INVALID
Greater than 0 T_INVALID
Greater than 0 No access to transport protocol addresses is provided.
Maximum size of a protocol address.
info->options T_INVALIDGreater than 0 T_INVALIDGreater than 0 No options.
Maximum number of bytes needed to hold protocol-
specific options.
info->tsdu 0
T_INVALID
Greater than 0 TSDUs not supported.
Transfer of normal data not supported.
Maximum size of a TSDU.
info->etsdu T_INFINITE
T_INVALID No limit on the size of an ETSDU.
Transfer of expedited data not supported.
info->connect T_INVALID T_INVALID Data cannot be sent with functions that establish connections.
info->discon T_INVALID T_INVALID Data cannot be sent with abortive disconnects.
info->servtype T_COTS
T_COTS_ORD T_CLTS Connection mode supported; orderly disconnects not supported.
Connection mode and orderly disconnects supported.
Connectionless mode supported.
info->flags T_SENDZERO T_SENDZERO Zero-length TSDUs supported.

IMPORTANT
The preceding table shows only what values are possible for each protocol. Be sure to to use the OTOpenEndpoint, OTAsyncOpenEndpoint, or OTGetEndpointInfo function to obtain the current values for these parameters.
These fields and the significance of their values are described in more detail in the document X/Open CAE Specification: X/Open Transport Interface (XTI).

Using Endpoint Functions With TCP/IP
This section describes protocol-specific information about functions described in the chapter "Endpoints" in this book. The functions are listed in the same order that they appear in that chapter.

OTBind
The OTBind function associates a local protocol address with the endpoint you specify. You must use this function for every protocol.
The addr field of the TBind structure refers to the local endpoint and so must specifically include a port number. Use an InetAddress structure (described in "Internet Address Structure" on page 8-22) to specify this address.
Because the architecture of Open Transport TCP/IP provides for multihoming (although this feature has not yet been implemented), you can specify an IP address of kOTAnyInetAddress to indicate that your application or process will accept packets from any TCP/IP interface that the user has configured in the TCP/IP control panel.
If you specify an address of 0 to the OTBind function, then the OTGetProtAddress function always returns an IP address of 0. In that case, you must use the OTInetGetInterfaceInfo function (page 8-50) to determine the IP address of a running IP interface. However, if you pass in a valid address with a port number of 0, the TCP/IP service provider assigns a port for you and the OTGetProtAddress function returns the assigned port number.
You can use the OTInetGetInterfaceInfo function (page 8-50) to get the IP addresses of all currently configured IP interfaces. Then, if you wish to receive packets from only a single interface, you can bind the endpoint to the address for that interface.

OTLook
The OTLook function checks for asynchronous events such as incoming data or connecton requests. You can use this function with any protocol.
As soon as a segment with the TCP urgent pointer set (that is, expedited data) enters the TCP receive buffer, TCP posts the T_EXDATA event. The T_EXDATA event remains posted until you have retrieved all data up to the byte pointed to by the TCP urgent pointer.

OTGetProtAddress
If you bind an endpoint to an IP address of 0 in order to accept packets from any valid TCP/IP interface, then the OTGetProtAddress function always returns an IP address of 0. This is because in a multihomed machine, there is a separate IP address for each interface, and there's no way for open transport to know which one you want. in that case, you must use the OTInetGetInterfaceInfo function (page 8-50) to determine the IP address of a running IP interface.
On the other hand, if you bind an endpoint to a specific interface, the OTGetProtAddress function returns the address of that interface, as expected.

OTConnect
The OTConnect function requests a connection to a specified remote endpoint. You can use this function with TCP but not with UDP or IP.
The rcvcall->addr field returns the same TNetbuf structure you specify in the sndcall->addr field.
Because TCP does not allow you to send any application-specific data during the connection establishment phase, you must set the sndcall->udata.len field to 0. TCP ignores any data in the sndcall->udata.buf field.
Note that TCP, not the receiving application, confirms the connection.

OTRcvConnect
The OTRcvConnect function reads the status of a previously issued connection request. You can use this function with TCP, but not with UDP or IP.
Because TCP does not allow you to send any application-specific data during the connection establishment phase, you must set the call->udata.maxlen field to 0. TCP ignores any data in the call->udata.buf field.
On return, the call->addr field points to the fully qualified internet address of the endpoint that accepted the connection.

OTListen
The OTListen function listens for an incoming connection request. You can use this function with TCP, but not with UDP or IP.
When the OTListen function successfully completes execution (that is, when you receive the T_LISTEN event), the call parameter describes a connection
that has already been completed at the TCP level. You use the OTAccept function to complete a connection at the application level. If you wish to reject a connection, you must call the OTSndDisconnect function after the OTListen function successfully completes execution.
Because TCP does not allow you to send any application-specific data during the connection establishment phase, you must set the call->udata.len field to 0. TCP ignores any data in the call->udata.buf field.

OTAccept
The OTAccept function accepts an incoming connection request. You can use this function with TCP, but not with UDP or IP.
Because TCP does not allow you to send any application-specific data during the connection establishment phase, you must set the call->udata.len field to 0. TCP ignores any data in the call->udata.buf field.
If you wish to send either of the association-related options (IP_OPTIONS or IP_TOS) with the connection confirmation, you must use the OTOptionManagement function to set the values of these options before you receive the T_LISTEN event. TCP has already established a connection when you receive the T_LISTEN event, and it is too late for the OTAccept function to negotiate these options.

OTSndUData
The OTSndUData function sends data through a connectionless transactionless endpoint. You can use this function with UDP and IP, but not with TCP.
The current value for the maximum size of a RawIP or UDP datagram is returned in the info->tsdu parameter of the OTOpenEndpoint, OTAsyncOpenEndpoint, and OTGetEndpointInfo functions.

OTSnd
The OTSnd function sends data through a connection-oriented transactionless endpoint. You can use this function with TCP, but not with UDP or IP.
TCP ignores the OTSnd function's T_MORE flag.
If you set the T_EXPEDITED flag, you must send at least 1 byte of data. If you call the OTSnd function with more than 1 byte specified and the T_EXPEDITED flag set, the TCP urgent pointer points to the last byte of the buffer.

OTRcv
The OTRcv function receives data through a connection-oriented endpoint. You can use this function with TCP, but not with UDP or IP.
Because TCP ignores the T_MORE flag when it is sending data and does not transmit the flag, you should ignore the T_MORE flag when receiving normal data. However, if a byte in the data stream is pointed to by the TCP urgent pointer, TCP receives this byte and as many bytes as possible preceding the marked byte with the T_EXPEDITED flag set. If your buffer is too small to receive all of the expedited data, TCP sets the T_MORE flag as well. Note that this situation might result in the number of bytes received as expedited data not being equal to the number of bytes sent by the originator as expedited data.

OTSndDisconnect
The OTSndDisconnect function initiates an abortive disconnect or rejects a connection request. You can use this function with TCP, but not with UDP or IP.
Because TCP does not allow you to send any application-specific data during a disconnect, you must set the call->udata.len field to 0. TCP ignores any data in the call->udata.buf field.

OTRcvDisconnect
The OTRcvDisconnect function returns information about why a connection attempt failed or an established connection was terminated. You can use this function with TCP, but not with UDP or IP.
Because TCP does not allow you to send any application-specific data during a disconnection, you must set the discon->udata.len field to 0. TCP ignores any data in the discon->udata.buf field.

Using Mapper Functions With TCP/IP
This section describes protocol-specific information about functions described in the chapter "Mappers" in this book. The functions are listed in the same order that they appear in that chapter.

OTRegisterName
Because the TCP/IP domain name system does not include a method for clients to register their names on the network, the Open Transport domain name resolver (DNR) does not support the OTRegisterName function. If you
call this function for a TCP/IP mapper, it will return the kOTNotSupportedErr result code.

OTDeleteName
This function is not supported by the TCP/IP domain name resolver (DNR).
If you call this function for a TCP/IP mapper, it will return the kOTNotSupportedErr result code.

OTLookupName
You can use the OTLookupName function to resolve a domain name to an internet address. Specify the name as a character string pointed to by the request->udata.buf parameter. The name can be just a host name (otteam), a partially qualified domain name ("otteam.ssw"), a fully qualified domain name ("otteam.ssw.apple.com."), or an internet address in dotted-decimal format ("17.202.99.99"), and can optionally include the port number ("otteam.ssw.apple.com:25" or "17.202.99.99:25").
The function returns a pointer to the address in the reply->udata.buf parameter. The address is in the format of an InetAddress structure (page 8-22), which includes the address type, the port number, and the IP address in hexadecimal format. If you don't specify a port number, the returned InetAddress structure contains a port number of 0. You can use this address directly in all Open Transport functions that require an internet address, such as OTConnect, OTSndUData, and OTBind.
The OTLookupName function returns only a single address, regardless of how many addresses are known for a single multihomed host. To obtain a list of up to 10 addresses for a multihomed host, use the OTStringToAddress function (page 8-40).

Parameter	TCP	RawIP and UDP	Meaning
info->addr	`T_INVALID` Greater than 0	`T_INVALID` Greater than 0	No access to transport protocol addresses is provided. Maximum size of a protocol address.
info->options	`T_INVALID`Greater than 0	`T_INVALID`Greater than 0	No options. Maximum number of bytes needed to hold protocol- specific options.
info->tsdu	0	`T_INVALID` Greater than 0	TSDUs not supported. Transfer of normal data not supported. Maximum size of a TSDU.
info->etsdu	`T_INFINITE`	`T_INVALID`	No limit on the size of an ETSDU. Transfer of expedited data not supported.
info->connect	`T_INVALID`	`T_INVALID`	Data cannot be sent with functions that establish connections.
info->discon	`T_INVALID`	`T_INVALID`	Data cannot be sent with abortive disconnects.
info->servtype	`T_COTS` `T_COTS_ORD`	`T_CLTS`	Connection mode supported; orderly disconnects not supported. Connection mode and orderly disconnects supported. Connectionless mode supported.
info->flags	`T_SENDZERO`	`T_SENDZERO`	Zero-length TSDUs supported.